<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
 <head>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <title>创建一个新的数据库连接对象</title>

 </head>
 <body><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="mongoclient.connect.html">MongoClient::connect</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="mongoclient.dropdb.html">MongoClient::dropDB</a></div>
 <div class="up"><a href="class.mongoclient.html">MongoClient</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="mongoclient.construct" class="refentry">
 <div class="refnamediv">
  <h1 class="refname">MongoClient::__construct</h1>
  <p class="verinfo">(PECL mongoclient &gt;=0.9.0)</p><p class="refpurpose"><span class="refname">MongoClient::__construct</span> &mdash; <span class="dc-title">创建一个新的数据库连接对象</span></p>

 </div>

 <div class="refsect1 description" id="refsect1-mongoclient.construct-description">
  <h3 class="title">说明</h3>
  <div class="constructorsynopsis dc-description">
   <span class="modifier">public</span> <span class="methodname"><strong>MongoClient::__construct()</strong></span>
    ([ <span class="methodparam"><span class="type">string</span> <code class="parameter">$server</code><span class="initializer"> = &quot;mongodb://localhost:27017&quot;</span></span>
   [, <span class="methodparam"><span class="type">array</span> <code class="parameter">$options</code><span class="initializer"> = array(&quot;connect&quot; =&gt; <strong><code>TRUE</code></strong>)</span></span>
  ]] )</div>

  <p class="para rdfs-comment">
   如果没有传入参数，它会连接到 &quot;localhost:27017&quot;（或者 php.ini 里指定的 <a href="mongo.configuration.html#ini.mongo.default-host" class="link">mongo.default_host</a> 和
   <a href="mongo.configuration.html#ini.mongo.default-port" class="link">mongo.default_port</a>）。
  </p>
  <p class="para">
   <em><code class="parameter">server</code></em> 应该是这样的形式：
   <div class="example-contents">
<div class="cdata"><pre>
mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db
</pre></div>
   </div>

  </p>
  <p class="para">
   连接字符串总是以 <em>mongodb://</em> 开头，表示它是一个连接字符串。
  </p>
  <p class="para">
   如果指定了 <em>username</em> 和 <em>password</em>，构造器会在返回前尝试验证连接数据库。
   用户名和密码是可选的，需要指定时必须紧随一个 <em>@</em>。
  </p>
  <p class="para">
   至少指定一个主机（端口可选，默认总是 27017），并且可以连接到想要数量的主机。
   主机名由逗号分隔，构造器会成功返回，如果连接到了至少一个主机。
   如果无法连接到任何主机，它将会抛出一个异常 <a href="class.mongoconnectionexception.html" class="classname">MongoConnectionException</a>。
  </p>
  <p class="para">
   如果你指定了一个用户名和密码，你可以指定一个要验证的数据库。
   如果没有指定 <em>db</em>，将会使用 &quot;admin&quot;。
  </p>
  <p class="para">
   可选的查询字符串可以用于指定额外的选项。
   同样参数也支持 <em><code class="parameter">options</code></em> 数组。
  </p>
  <p class="para">
   选项的一部分指示了驱动在集群环境下对备份节点如何读取。
   关于读取首选项运行的额外信息可以查找 <a href="mongo.readpreferences.html" class="link">读取首选项</a> 文档页面。
  </p>
 </div>


 <div class="refsect1 parameters" id="mongo.mongoclient.construct.parameters">
  <h3 class="title">参数</h3>
  <p class="para">
   <dl>

    
     <dt>

      <em><code class="parameter">server</code></em>
     </dt>

     <dd>

      <p class="para">
       服务器名。
      </p>
     </dd>

    
    
     <dt>

      <em><code class="parameter">options</code></em>
     </dt>

     <dd>

      <p class="para">
       此连接的数组选项。当前有效的选项包括了：
       <ul class="itemizedlist">
        <li class="listitem">
         <p class="para">
          <em>&quot;connect&quot;</em>
         </p>
         <p class="para">
          构造器是否应该在返回前连接。
          默认为 <strong><code>TRUE</code></strong>。当设置为 <strong><code>FALSE</code></strong>，驱动会在有查询必要时
          <em class="emphasis">自动</em> 连接到服务器。
          另外，你也可以用
          <span class="function"><a href="mongoclient.connect.html" class="function">MongoClient::connect()</a></span> 手动运行。
         </p>
         <div class="warning"><strong class="warning">Warning</strong>
          <p class="para">
           这个选项不支持通过连接字符串来设置。
          </p>
         </div>
        </li>
        <li class="listitem">
         <p class="para">
          <em>&quot;db&quot;</em>
         </p>
         <p class="para">
          要验证的数据库能在这里指定，而不是在主机列表中包含它。
          能够重载主机列表中指定的数据库。
         </p>
        </li>
        <li class="listitem">
         <p class="para">
          <em>&quot;password&quot;</em>
         </p>
         <p class="para">
          能在这里指定密码，而不是在主机列表中指定。
          当密码里有一个 &quot;@&quot; 的时候尤其有用。
          此参数会覆盖主机列表中设置的密码。
         </p>
        </li>
        <li class="listitem">
         <p class="para">
          <em>&quot;readPreference&quot;</em>
         </p>
         <p class="para">
          指定读取首选项类型。
          读取首选项提供了对备份数据读取的控制。
         </p>
         <p class="para">
          允许的值有： <strong><code>MongoClient::RP_PRIMARY</code></strong>、
          <strong><code>MongoClient::RP_PRIMARY_PREFERRED</code></strong>、
          <strong><code>MongoClient::RP_SECONDARY</code></strong>、
          <strong><code>MongoClient::RP_SECONDARY_PREFERRED</code></strong> 和
          <strong><code>MongoClient::RP_NEAREST</code></strong>。
         </p>
         <p class="para">
          更多信息参见<a href="mongo.readpreferences.html" class="link">读取首选项</a>文档。
         </p>
        </li>
        <li class="listitem">
         <p class="para">
          <em>&quot;readPreferenceTags&quot;</em>
         </p>
         <p class="para">
          以字符串的数组指定读取选项标签。
          标签能够控制 <em>readPreference</em> 选项来进一步控制从备份节点数据的读取。
         </p>
         <p class="para">          
          更多信息参见<a href="mongo.readpreferences.html" class="link">读取首选项</a>文档。
         </p>
        </li>
        <li class="listitem">
         <p class="para">
          <em>&quot;replicaSet&quot;</em>
         </p>
         <p class="para">
          要连接的集群名称。
          如果指定了，活跃节点能够自动检测到。
          这意味着驱动能够最终甚至能够连接到未列出的服务器。
          更多细节参见集群的例子。
         </p>
        </li>
        <li class="listitem">
         <p class="para">
          <em>&quot;connectTimeoutMS&quot;</em>
         </p>
         <p class="para">
          打开连接超时的时间。
         </p>
        </li>
        <li class="listitem">
         <p class="para">
          <em>&quot;timeout&quot;</em>
         </p>
         <p class="para">
          &quot;connectTimeoutMS&quot; 废弃的别名。
         </p>
        </li>
        <li class="listitem">
         <p class="para">
          <em>&quot;socketTimeoutMS&quot;</em>
         </p>
         <p class="para">
          在套接字上发送或接收超时的时间。
          <blockquote class="note"><p><strong class="note">Note</strong>: 
           <span class="simpara">
            这是客户端的超时时间。如果一个 <em>insert</em> 达到了 socketTimeoutMS，
            将无法得知服务器是否确实已写入。
           </span>
          </p></blockquote>
         </p>
        </li>
        <li class="listitem">
         <p class="para">
          <em>&quot;username&quot;</em>
         </p>
         <p class="para">
          能在这里指定用户名，而不是在主机列表中指定。
          当用户名包括一个「:」时尤其有用。
          它会覆盖主机列表中的设置。
         </p>
        </li>
        <li class="listitem">
         <p class="para">
          <em>&quot;w&quot;</em>
         </p>
         <p class="para">
          选项 <em>w</em> 指定了驱动的
          <a href="mongo.writeconcerns.html" class="link">Write Concern</a>，决定了驱动在写入时阻塞的时间。
          默认值是 <em>1</em>。
         </p>
         <p class="para">
          此选项适用于单台服务器或者是集群。
          一个正数值控制了在驱动继续之前，有<em class="emphasis">多少个</em>节点必须应答写入的指令。
          值 <em>1</em> 将让单台服务器或者活跃节点（在集群里）应答写入操作。
          值 <em>3</em> 将阻塞驱动直至写入到活跃节点和其他两个备份节点服务器（在集群里）。
         </p>
         <p class="para">
          一个字符串的值用于控制考虑 write concerns 的标签集。
          <em>&quot;majority&quot;</em> 是特殊用于确保写入操作被应用于大多数（大于 50%）参与的节点。
         </p>
        </li>
        <li class="listitem">
         <p class="para">
          <em>&quot;wTimeout&quot;</em>
         </p>
         <p class="para">
          此选项用于和 <em>&quot;w&quot;</em> 参数组合使用。
          它控制了服务器等待多少毫秒来满足 write concern。
          如果超时了，驱动会抛出 <a href="class.mongocursorexception.html" class="classname">MongoCursorException</a> 异常。
         </p>
        </li>
       </ul>
      </p>
     </dd>

    
   </dl>

  </p>
 </div>


 <div class="refsect1 returnvalues" id="refsect1-mongoclient.construct-returnvalues">
  <h3 class="title">返回值</h3>
  <p class="para">
   返回一个新的数据库连接对象。
  </p>
 </div>


 <div class="refsect1 errors" id="refsect1-mongoclient.construct-errors">
  <h3 class="title">错误／异常</h3>
  <p class="para">
   如果给出的主机都无法连接，将会抛出 <a href="class.mongoconnectionexception.html" class="classname">MongoConnectionException</a> 异常。
   
   如果提供了无效的用户名和密码将会抛出一个 <strong class="classname">MongoConnnectionException</strong>。
   
   参见 <a href="class.mongoconnectionexception.html" class="classname">MongoConnectionException</a> 相关文档获取异常发生的原因。
  </p>
 </div>


 <div class="refsect1 changelog" id="refsect1-mongoclient.construct-changelog">
  <h3 class="title">更新日志</h3>
  <p class="para">
   <table class="doctable informaltable">
    
     <thead>
      <tr>
       <th>版本</th>
       <th>说明</th>
      </tr>

     </thead>

     <tbody class="tbody">
      <tr>
       <td>1.3.4</td>
       <td>
        <p class="para">
         添加了 <em>&quot;connectTimeoutMS&quot;</em> 和
         <em>&quot;socketTimeoutMS&quot;</em> 选项。
        </p>
       </td>
      </tr>

      <tr>
       <td>1.3.0</td>
       <td>
        <p class="para">
         添加了 <em>&quot;readPreference&quot;</em>、
         <em>&quot;readPreferenceTags&quot;</em>、<em>&quot;w&quot;</em> 和
         <em>&quot;wTimeout&quot;</em> 选项。
        </p>
       </td>
      </tr>

      <tr>
       <td>1.2.0</td>
       <td>
        <p class="para">
         添加了 <em>&quot;username&quot;</em> 和
         <em>&quot;password&quot;</em> 选项。
        </p>
        <p class="para">
         移除了 <em>&quot;persist&quot;</em> 选项，所有的连接都是持久的。它仍旧能够使用，但是不起作用。
        </p>
        <dl>

         
          <dt>

           <em><code class="parameter">&quot;persist&quot;</code></em>
          </dt>

          <dd>

           <p class="para">
            是否应该是持久连接。如果设置了，连接会是持久连接。
            字符形式的值将会用于连接的 ID。所以两个以 <em>array(&quot;persist&quot; =&gt; &quot;foobar&quot;)</em> 初始化的 <a href="class.mongoclient.html" class="classname">MongoClient</a> 实例会共享一个数据库连接，以 <em>array(&quot;persist&quot; =&gt; &quot;barbaz&quot;)</em>初始化的实例则使用不同的数据库连接。
           </p>
          </dd>

         
        </dl>

        <p class="para">
         <em>&quot;replicaSet&quot;</em> 选项现在支持一个字符串，而不是布尔值。
        </p>
       </td>
      </tr>

      <tr>
       <td>1.0.9</td>
       <td>添加了 <em>&quot;replicaSet&quot;</em> 选项。</td>
      </tr>

      <tr>
       <td>1.0.2</td>
       <td>
        <p class="para">
         修改构造器支持选修数组。在 1.0.2 之前，构造器接受以下参数：
        </p>
        <dl>

         
          <dt>

           <em><code class="parameter">server</code></em>
          </dt>

          <dd>

           <p class="para">
            服务器名。
           </p>
          </dd>

         
         
          <dt>

           <em><code class="parameter">connect</code></em>
          </dt>

          <dd>

           <p class="para">
            可选的 boolean 参数指定了构造器是否应该在返回前连接到数据库。默认为 <strong><code>TRUE</code></strong>。
           </p>
          </dd>

         
         
          <dt>

           <em><code class="parameter">persistent</code></em>
          </dt>

          <dd>

           <p class="para">
            连接是否应该是持久的。
           </p>
          </dd>

         
         
          <dt>

           <em><code class="parameter">paired</code></em>
          </dt>

          <dd>

           <p class="para">
            连接是否应该为 paired 模式。
           </p>
          </dd>

         
        </dl>

       </td>
      </tr>

     </tbody>
    
   </table>

  </p>
 </div>


 <div class="refsect1 examples" id="refsect1-mongoclient.construct-examples">
  <h3 class="title">范例</h3>
  <div class="example" id="example-1369">
   <p><strong>Example #1 <span class="function"><strong>MongoClient::__construct()</strong></span> 集群例子</strong></p>
   <div class="example-contents"><p>
    这个例子显示了如何连接本驱动到一个集群。
    它假设了有三个服务器的集群： sf1.example.com、sf2.example.com 和 ny1.example.com。
    活跃节点可能是其中任意一个。
   </p></div>
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /><br /></span><span style="color: #FF8000">//&nbsp;传递逗号分隔的服务器名称列表到构造器<br />//&nbsp;注意我们不需要传入集群的所有成员，驱动能够获取完整的列表<br /></span><span style="color: #0000BB">$m1&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">MongoClient</span><span style="color: #007700">(</span><span style="color: #DD0000">"mongodb://sf2.example.com,ny1.example.com"</span><span style="color: #007700">,&nbsp;array(</span><span style="color: #DD0000">"replicaSet"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">"myReplSet"</span><span style="color: #007700">));<br /><br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
   </div>

   <div class="example-contents"><p>
    如果当前活跃节点连接失败，驱动会计算出备用节点服务器作为新的活跃节点，并自动启用该连接。
    如果没有指定 <em>replicaSet</em>，自动容错移转将无法正常工作。
   </p></div>
   <div class="example-contents"><p>
    在驱动连接的集群种子列表里，起码要有一个种子是在线的。
   </p></div>
   <div class="example-contents"><p>
    如果你包含的种子位于两个独立的集群，后面的行为将不可预测。
   </p></div>
   <div class="example-contents"><p>
    更多关于集群的信息参见<a href="http://docs.mongodb.org/manual/replication/" class="link external">&raquo;&nbsp;核心文档</a>。
   </p></div>
  </div>
  <div class="example" id="example-1370">
   <p><strong>Example #2 连接到一个域套接字（domain socket）</strong></p>
   <div class="example-contents"><p>
    在 1.0.9+ 版本中，你可以使用一个 UNIX 域套接字来连接到一个本地的 MongoDB 实例。
    这可能会比使用网络连接稍微快一点。
   </p></div>
   <div class="example-contents"><p>
    在版本 1.5.0，MongoDB 服务器会自动打开 /tmp/mongodb-&lt;port&gt;.sock 上的套接字。
    你可以在连接字符串中指定位置：
   </p></div>
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /><br /></span><span style="color: #FF8000">//&nbsp;MongoDB&nbsp;服务器运行在本地&nbsp;20000&nbsp;端口上<br /></span><span style="color: #0000BB">$m&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">MongoClient</span><span style="color: #007700">(</span><span style="color: #DD0000">"mongodb:///tmp/mongodb-20000.sock"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
   </div>

   <div class="example-contents"><p>
    你也可以和其他想要的连接组合：
   </p></div>
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /><br /></span><span style="color: #FF8000">//&nbsp;尝试连接到套接字，失败时使用&nbsp;localhost&nbsp;连接<br /></span><span style="color: #0000BB">$m&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">MongoClient</span><span style="color: #007700">(</span><span style="color: #DD0000">"mongodb:///tmp/mongodb-27017.sock,localhost:27017"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
   </div>

  </div>
  <div class="example" id="example-1371">
   <p><strong>Example #3 <span class="function"><strong>MongoClient::__construct()</strong></span> 验证的例子</strong></p>
   <div class="example-contents"><p>
    在尝试验证时，用户必须存在于 admin 数据库。
    你可以通过终端，用 Mongo 创建一个：
   </p></div>
   <div class="example-contents">
<div class="cdata"><pre>
&gt; use admin
switched to db admin
&gt; db.addUser(&quot;testUser&quot;, &quot;testPass&quot;);
{
        &quot;_id&quot; : ObjectId(&quot;4b21272fd9ab21611d19095c&quot;),
        &quot;user&quot; : &quot;testUser&quot;,
        &quot;pwd&quot; : &quot;03b9b27e0abf1865e2f6fcbd9845dd59&quot;
}
&gt;
</pre></div>
   </div>

   <div class="example-contents"><p>
    创建一个用户后，上面的例子里用户名为 &quot;testUser&quot; 并且密码为 
    &quot;testPass&quot;，你可以创建一个验证后的连接：
   </p></div>
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /><br />$m&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">MongoClient</span><span style="color: #007700">(</span><span style="color: #DD0000">"mongodb://testUser:testPass@localhost"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
   </div>

  </div>
  <div class="example" id="example-1372">
   <p><strong>Example #4 <span class="function"><strong>MongoClient::__construct()</strong></span> 读取选项例子</strong></p>
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /><br /></span><span style="color: #FF8000">//&nbsp;首选&nbsp;"east"&nbsp;数据中心最近的服务器<br /></span><span style="color: #0000BB">$uri&nbsp;&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #DD0000">'mongodb://rs1.example.com,rs2.example.com/'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$uri&nbsp;</span><span style="color: #007700">.=&nbsp;</span><span style="color: #DD0000">'?readPreference=nearest'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$uri&nbsp;</span><span style="color: #007700">.=&nbsp;</span><span style="color: #DD0000">'&amp;readPreferenceTags=dc:east'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$m&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">MongoClient</span><span style="color: #007700">(</span><span style="color: #0000BB">$uri</span><span style="color: #007700">,&nbsp;array(</span><span style="color: #DD0000">'replicaSet'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">'rs'</span><span style="color: #007700">));</span>
</span>
</code></div>
   </div>

   <div class="example-contents"><p>
    更多信息参见本手册中<a href="mongo.readpreferences.html" class="link">读取选项</a>一节。
   </p></div>
  </div>
 </div>


</div><hr /><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="mongoclient.connect.html">MongoClient::connect</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="mongoclient.dropdb.html">MongoClient::dropDB</a></div>
 <div class="up"><a href="class.mongoclient.html">MongoClient</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
